Enterprise Objects Framework Release 1.1 Copyright ã1995 by NeXT Computer, Inc.  All Rights Reserved.

EOQualifier

Inherits From:	NSObject

Conforms To:	NSCopying

Declared In:	eoaccess/EOQualifier.h

Class Description

An EOQualifier holds information used to restrict a select operation to enterprise objects or rows whose attributes have certain values. A qualifier is always created for a specific entity and has a definition based on attributes of that entity. The qualifying information is expressed in the database server's query language (nearly always SQL). You can build a qualifier directly from an existing enterprise object or row fetched from the database or with a printf()-style format string.

Creating a Qualifier For a Primary Key or Relationship

EOQualifier defines two class methods for quickly creating simple qualifiers. You can create an EOQualifier that selects only one record, based on a primary key value for an entity, with the qualifierForPrimaryKey:entity: class method. Such a qualifier merely requires the value for the primary key to be equal to the value you provide to this method. Similarly, you can create an EOQualifier to fetch the destination record(s) of a relationship with qualifierForRow:relationship:. In this case the qualifier requires the foreign keys of the row provided to match the join attributes in the destination entity of the relationship.

Creating a Qualifier From A Format String

You can also create a qualifier with a general string definition. This definition can be any valid SQL search condition using the internal names of properties belonging to the qualifier's entity (they're converted to database column names before being sent to the server). It may contain generic SQL, or include server-specific operators or references to features such as stored procedures. You're responsible for ensuring that the SQL used is valid for your database server.

For example, if you have an Employee entity with the properties empID, firstName, lastName, salary, and toDepartment, and a Department entity with properties deptID, and name, the following are valid qualifier strings:

lastName = 'Smith'
salary > 2500
toDepartment.name = 'Personnel'

You create a qualifier from a string by using initWithEntity:qualifierFormat:. This method takes as arguments the root entity for the qualifier and a format string somewhat like that used with the standard C printf() function. The format string can embed strings, numbers, and objects using the conversion specifications listed below. This allows qualifiers to be built dynamically.

Format Symbol	Expected Value or Result

%s	A constant C string (const char *).

%A	An NSString, which is resolved as a property name.

%d	An int.

%f	A float or double.

%@	An id argumentÐvalid objects are EOAttribute, NSString, or anything that responds to expressionValueForContext:.

%%	Results in a literal % character.

%	Followed by any other character results in that character appearing in the string.

The following examples build qualifiers similar to the qualifier strings described above, but take the specific values from an already-fetched enterprise object:

myQualifier = [[EOQualifier alloc] initWithEntity:employeeEntity
    qualifierFormat:@"%A = '%@'", @"lastName", [anEmployee lastName]];
myQualifier = [[EOQualifier alloc] initWithEntity:employeeEntity
    qualifierFormat:@"%A > %f", @"salary", [anEmployee salary]];
myQualifier = [[EOQualifier alloc] initWithEntity:employeeEntity
    qualifierFormat:@"%A = '%@'", @"toDepartment.name", [aDept name]];

The enterprise objects here implement convenience methods for directly accessing the given attributes: lastName and salary for Employee objects, and name for Department objects.

These first examples assume that the string values in the qualifier must be enclosed in single quotation marks. This may not always be a valid assumption, so if you want to be sure your qualifiers are using the proper formats for your database you can ask the adaptor to format both your attribute names and values for inclusion in a qualifier. The next example uses EOAdaptor's formatAttribute: and formatValue:forAttribute: methods to be sure that the qualifier string is well-formed for the database. In this case, since the attribute is a string type, formatValue:forAttribute: returns a quoted copy of the string with any embedded quotes suitably escaped.

EOAdaptor *myAdaptor;             /* Assume this exists. */
EOAttribute *lastNameAttribute;   /* Assume this exists. */
EOEntity *employeeEntity;         /* Assume this exists. */
id formattedAttribute;
id formattedValue;
EOQualifier *aQualifier;

formattedAttribute = [myAdaptor formatAttribute:lastNameAttribute];
formattedValue = [myAdaptor formatValue:[anEmployee lastName]
    forAttribute:lastNameAttribute];

aQualifier = [[EOQualifier alloc] initWithEntity:employeeEntity
    qualifierFormat:@"%@ = %@", formattedAttribute, formattedValue];

Though you can usually include an attribute reference directly as a string without any problems, it's a good idea to use formatValue:forAttribute: for values whenever you build a query.

Instance Variables

None declared in this class.

Adopted Protocols

NSCopying	- copy
- copyWithZone:

Method Types

Creating instances	+ qualifierForPrimaryKey:entity:
+ qualifierForRow:relationship:
- initWithEntity:qualifierFormat:

Combining qualifiers	- conjoinWithQualifier:
- disjoinWithQualifier:
- negate

Getting the entity	- entity

Checking the definition	- isEmpty

Setting distinct selection	- setUsesDistinct:
- usesDistinct

Class Methods

qualifierForPrimaryKey:entity:

+ (EOQualifier *)qualifierForPrimaryKey:(NSDictionary *)aKey entity:(EOEntity *)anEntity

Returns a qualifier that selects only the object in anEntity's table that has aKey as its primary key.

qualifierForObject:relationship:

+ (EOQualifier *)qualifierForObject:(id)anObject relationship:(EORelationship *)aRelationship

Returns a qualifier that selects only the row for aRelationship's destination entity whose primary key matches anObject's foreign key for aRelationship.

See also:  +qualifierForRow:relationship:, - destinationEntity (EORelationship)

qualifierForRow:relationship:

+ (EOQualifier *)qualifierForRow:(NSDictionary *)aRow relationship:(EORelationship *)aRelationship

Returns a qualifier that selects only the row for aRelationship's destination entity whose primary key matches aRow's foreign key for aRelationship.

See also:  +qualifierForObject:relationship:, - destinationEntity (EORelationship)

Instance Methods

conjoinWithQualifier:

- (void)conjoinWithQualifier:(EOQualifier *)aQualifier

Replaces the contents of the receiver with the conjunction (logical AND) of the existing contents and the aQualifier. For example, this code excerpt creates a qualifier that selects employees whose salaries are between 4000 and 5000, inclusive:

EOEntity *employeeEntity;        /* Assume this exists. */
EOAttribute *salaryAttribute;    /* Assume this exists. */
EOQualifier *lowQualifier;
EOQualifier *combinedQualifier;

lowQualifier = [[EOQualifier alloc] initWithEntity:employeeEntity
    formatString:@"%@ >= 4000", salaryAttribute];

combinedQualifier = [[EOQualifier alloc] initWithEntity:employeeEntity
    formatString:@"%@ <= 5000", salaryAttribute];

[combinedQualifier conjoinWithQualifier:lowQualifier];

disjoinWithQualifier:

- (void)disjoinWithQualifier:(EOQualifier *)aQualifier

Replaces the contents of the receiver with the disjunction (logical OR) of the existing contents and the aQualifier. For example, this code excerpt creates a qualifier that selects all employees in both the Personnel and Administration departments:

EOAdaptor *myAdaptor;              /* Assume this exists. */
EOEntity *employeeEntity;          /* Assume this exists. */
EOAttribute *deptNameAttribute;    /* Assume this exists. */
id tempValue;
EOQualifier *persQualifier;
EOQualifier *combinedQualifier;

tempValue = [myAdaptor formatValue:@"Personnel"
    forAttribute:deptNameAttribute];
persQualifier = [[EOQualifier alloc] initWithEntity:employeeEntity
    formatString:@"%@ = %@", deptNameAttribute, tempValue];

tempValue = [myAdaptor formatValue:@"Administration"
    forAttribute:deptNameAttribute];
combinedQualifier = [[EOQualifier alloc] initWithEntity:employeeEntity
    formatString:@"%@ = %@", deptNameAttribute, tempValue];

[combinedQualifier conjoinWithQualifier:persQualifier];

entity

- (EOEntity *)entity

Returns the entity that defines the context for attributes and relationships. Any attribute named in the qualifier must belong to this entity, and data paths must begin with a relationship defined in this entity.

initWithEntity:qualifierFormat:

- initWithEntity:(EOEntity *)anEntity qualifierFormat:(NSString *)format, ...

Initializes a newly allocated EOQualifier to be rooted in anEntity and to build itself from a format string. The string is a printf()-style format string as presented in the class description. This is the designated initializer for the EOQualifier class. Returns self if format is successfully parsed, nil otherwise.

isEmpty

- (BOOL)isEmpty

Returns YES if the receiver selects all rows for its entity (that is, if it has no qualifying information beyond the entity). Returns NO otherwise.

negate

- (void)negate

Negates the receiver's qualifying information.

setUsesDistinct:

- (void)setUsesDistinct:(BOOL)flag

Sets according to flag whether the receiver eliminates duplicates from the results of a select operation. If a select operation would yield the same row many times, a qualifier that uses distinct results eliminates all duplicates so that only one is retrieved.

Note:  If you send setUsesDistinct:YES to an EOQualifier and then conjoin that qualifier with another that doesn't use distinct results, the resulting qualifier won't use distinct results.

See also:  conjoinWithQualifier:, usesDistinct

usesDistinct

- (BOOL)usesDistinct

Returns YES if the receiver eliminates duplicates from the results of a select operation, NO if it doesn't. If a select operation would yield the same row many times, a qualifier that uses distinct results eliminates all duplicates so that only one is retrieved.

See also:  setUsesDistinct: